---
title: Publique no NPM
description: Aprenda como publicar componentes Astro no NPM
i18nReady: true
---
import { FileTree } from '@astrojs/starlight/components';

Está construindo um novo componente Astro? **Publique-o ao [npm!](https://npmjs.com/)**

Publicar um componente Astro é uma ótima forma de reutilizar o seu trabalho entre projetos e o compartilhar com a grande comunidade do Astro. Componentes Astro podem ser publicados diretamente e instalados pelo NPM, assim como qualquer outro pacote JavaScript.

Procurando por inspiração? Veja alguns dos nossos [temas](https://astro.build/themes/) e [componentes](https://astro.build/integrations/) favoritos da comunidade do Astro. Você também pode [pesquisar pelo npm](https://www.npmjs.com/search?q=keywords:astro-component,withastro) para ver o catálogo público inteiro.

:::tip[Não quer começar do zero?]
Veja o [template de componentes da comunidade do Astro](https://github.com/astro-community/component-template) e comece com um template mantido pela comunidade!
:::

## Início Rápido

Para começar a desenvolver seu componente rapidamente, você pode usar um template configurado para você.

```bash
# Inicialize o template de Componente Astro em um novo diretório
npm create astro@latest diretorio-do-meu-novo-componente -- --template component
# yarn
yarn create astro diretorio-do-meu-novo-componente --template component
# pnpm
npm create astro@latest diretorio-do-meu-novo-componente -- --template component
```

## Criando um pacote

:::note[Pré-requisitos]
Antes de se aprofundar, será útil ter um entendimento básico de:

- [Módulos Node](https://docs.npmjs.com/creating-node-js-modules)
- [Manifesto do Pacote (`package.json`)](https://docs.npmjs.com/creating-a-package-json-file)
- [Workspaces](https://docs.npmjs.com/cli/v7/configuring-npm/package-json#workspaces)
:::


Para criar um pacote, configure seu ambiente de desenvolvimento para utilizar **workspaces** em um projeto. Isso irá permitir que você desenvolva o seu componente ao lado de uma cópia funcional do Astro.

<FileTree>
- diretorio-do-meu-novo-componente/
  - demo/
    - ... para testes e demonstração
  - package.json
  - packages/
    - meu-componente/
      - index.js
      - package.json
      - ... arquivos adicionais utilizados pelo pacote
</FileTree>

Esse exemplo, chamado de `meu-projeto`, cria um projeto com um único pacote, chamado de `meu-componente` e um diretório `demo` para testes e demonstração do componente.

Isso é configurado no arquivo da raiz do projeto `package.json`:

```json
{
  "name": "meu-projeto",
  "workspaces": ["demo", "packages/*"]
}
```

Nesse exemplo, múltiplos pacotes podem ser desenvolvidos juntos a partir do diretório `packages`. Esses pacotes podem ser referenciados de `demo`, aonde você pode instalar uma cópia funcional do Astro.

```shell
npm create astro@latest demo -- --template minimal
# yarn
yarn create astro my-new-component-directory --template minimal
# pnpm
pnpm create astro@latest my-new-component-directory -- --template minimal
```

Há dois arquivos iniciais que irão fazer parte do seu pacote individual: `package.json` e `index.js`.

### `package.json`

O `package.json` no diretório do pacote inclui todas as informações relacionadas ao seu pacote, como sua descrição, dependências e outros metadados do pacote.

```json
{
  "name": "meu-componente",
  "description": "Descrição do componente",
  "version": "1.0.0",
  "homepage": "https://github.com/dono/projeto#readme",
  "type": "module",
  "exports": {
    ".": "./index.js",
    "./astro": "./MeuComponenteAstro.astro",
    "./react": "./MeuComponenteReact.jsx"
  },
  "files": ["index.js", "MeuComponenteAstro.astro", "MeuComponenteReact.jsx"],
  "keywords": ["astro", "withastro", "astro-component", "...", "..."]
}
```

#### `description`

Uma pequena descrição do seu componente, utilizada para ajudar outros a entender o que seu pacote faz.

```json
{
  "description": "Um gerador de elementos Astro"
}
```

#### `type`

O formato de módulo utilizado pelo Node.js e pelo Astro para interpretar seus arquivos `index.js`.

```json
{
  "type": "module"
}
```

Use `"type": "module"` para que assim seu `index.js` possa ser usado como ponto de entrada com `import` e `export`.

#### `homepage`

A url da página inicial do seu projeto.

```json
{
  "homepage": "https://github.com/dono/projeto#readme"
}
```

Essa é uma ótima forma de direcionar usuários a uma demonstração online, documentação ou a página inicial do seu projeto.

#### `exports`

Os pontos de entrada de um pacote quando importado pelo seu nome.

```json
{
  "exports": {
    ".": "./index.js",
    "./astro": "./MeuComponenteAstro.astro",
    "./react": "./MeuComponenteReact.jsx"
  }
}
```

Neste exemplo, importar `meu-componente` utilizaria `index.js`, enquanto importar `meu-componente/astro` ou `meu-componente/react` utilizaria `MeuComponenteAstro.astro` ou `MeuComponenteReact.jsx` respectivamente.

#### `files`

Uma otimização opcional para excluir arquivos desnecessários do empacotamento enviado aos usuários via npm. Note de que **apenas arquivos listados aqui serão incluídos no seu pacote**, então se você adicionar ou modificar arquivos necessários para seu pacote funcionar, você precisar atualizar essa lista de acordo.

```json
{
  "files": ["index.js", "MeuComponenteAstro.astro", "MeuComponenteReact.jsx"]
}
```

#### `keywords`

Um array de palavras-chave relevantes para o seu componente, utilizado para ajudar outros a encontrar [seu pacote no npm](https://www.npmjs.com/search?q=keywords:astro-component,withastro) e em outros catálogos de pesquisa.

Adicione `astro-component` ou `withastro` como uma palavra-chave especial para maximizar a sua descoberta no ecossistema Astro.

```json
{
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}
```

:::tip
Palavras-chave também são utilizadas por nossa [biblioteca de integrações](https://astro.build/integrations/)! [Veja abaixo](#biblioteca-de-integrações) para uma lista completa das palavras-chave que procuramos no NPM.
:::

---

### `index.js`

O **ponto de entrada principal do pacote** é utilizado sempre que seu pacote é importado.

```js
export { default as MeuComponenteAstro } from './MeuComponenteAstro.astro';

export { default as MeuComponenteReact } from './MeuComponenteReact';
```

Isso permite que você empacote múltiplos componentes juntos em uma única interface.

#### Exemplo: Utilizando Importações Nomeadas

```astro
---
import { MeuComponenteAstro } from 'meu-componente';
import { MeuComponenteReact } from 'meu-componente';
---
<MeuComponenteAstro />
<MeuComponenteReact />
```

#### Exemplo: Utilizando Importações de Namespace

```astro
---
import * as Exemplo from 'componente-astro-exemplo';
---
<Exemplo.MeuComponenteAstro />
<Exemplo.MeuComponenteReact />
```

#### Exemplo: Utilizando Importações Individuais

```astro
---
import MeuComponenteAstro from 'componente-astro-exemplo/astro';
import MeuComponenteReact from 'componente-astro-exemplo/react';
---
<MeuComponenteAstro />
<MeuComponenteReact />
```

---

## Desenvolvendo seu pacote 

Astro não possui um "modo pacote" dedicado para desenvolvimento. Nesse caso, você deve utilizar um projeto demonstrativo para desenvolver e testar seu pacote dentro do seu projeto. Pode ser um website privado apenas para desenvolvimento ou uma demonstração/documentação pública para o seu pacote.

Se você estiver extraindo componentes de um projeto existente, você pode até mesmo continuar a utilizar aquele projeto para desenvolver os seus componentes extraídos.

## Testando seu componente

Astro atualmente não vem com um executador de testes. _(Se você estiver interessado em ajudar com isso, [junte-se a nós no Discord!](https://astro.build/chat))_

Enquanto isso, nossas recomendações atuais para testes é: 

1. Adicionar um diretório `fixtures` ao seu diretório `demo/src/pages`.
2. Adicionar uma nova página para cada teste que você deseja executar.
3. Cada página deve ter algum uso diferente do componente que você gostaria de testar.
4. Execute `astro build` para construir suas fixtures, então compare o resultado final do diretório `dist/__fixtures__/` com o resultado esperado.

<FileTree>
- meu-projeto/demo/src/pages/\_\_fixtures\_\_/
  - nome-teste-01.astro
  - nome-teste-02.astro
  - nome-teste-03.astro
</FileTree>

## Publicando seu componente

Assim que você tiver seu pacote pronto, você pode publicá-lo no npm usando o comando `npm publish`. Se o comando falhar, certifique-se de que você está logado via `npm login` e que seu `package.json` está correto. Se o comando funcionou, você terminou!

Entenda que não há uma etapa de `build` para pacotes Astro. Quaisquer tipos de arquivos que o Astro suporta, como `.astro`, `.ts`, `.jsx` e `.css`, podem ser publicados diretamente sem uma etapa de construção.

Se você precisar de outro tipo de arquivo que não é nativamente suportado pelo Astro, adicione uma etapa de construção ao seu pacote. Esta prática avançada fica por sua conta.

## Biblioteca de Integrações

Compartilhe o seu trabalho árduo adicionando sua integração a nossa [biblioteca de integrações](https://astro.build/integrations/)!

### Dados do `package.json` 

A biblioteca é automaticamente atualizada toda noite, puxando cada pacote publicado no NPM com a palavra-chave `astro-component` ou `withastro`.

A biblioteca de integrações lê os dados `name`, `description`, `repository` e `homepage` do seu `package.json`.

Avatars são uma ótima forma de destacar a sua marca na biblioteca! Assim que seu pacote estiver publicado você pode [adicionar um GitHub issue](https://github.com/withastro/astro.build/issues/new/choose) com o seu avatar anexado e nós iremos adicionar a sua listagem.

:::tip
Precisa sobrescrever a informação que nossa biblioteca lê do NPM? Sem problema! [Adicione uma issue](https://github.com/withastro/astro.build/issues/new/choose) com as informações atualizadas e nós nos certificaremos que o `name`, `description` ou `homepage` customizado seja utilizado no lugar.
:::

### Coleções

Em adição a palavra-chave obrigatória `astro-component` ou `withastro`, palavras-chave especiais são utilizadas para automaticamente organizar pacotes. Incluindo qualquer uma das palavras-chave abaixo irão adicionar sua integração a uma coleção em nossa biblioteca de integrações. 

| coleção           | palavras-chave                               |
|------------------ | -------------------------------------------- |
| Acessibilidade    | `a11y`, `accessibility`                      |
| Adaptadores       | `astro-adapter`                              |
| Analytics         | `analytics`                                  |
| CSS + UI          | `css`, `ui`, `icon`, `icons`, `renderer`     |
| Frameworks        | `renderer`                                   |
| Performance + SEO | `performance`, `perf`, `seo`, `optimization` |

## Compartilhe

Nós incentivamos que você compartilhe o seu trabalho, assim como amamos ver o que nossos talentosos Astronautas criaram. Venha e compartilhe o que você criou conosco em nosso [Discord](https://astro.build/chat) ou mencione [@astrodotbuild](https://twitter.com/astrodotbuild) em um Tweet!
